Move documentation from templates to inline comments: GtkAboutDialog

https://bugzilla.gnome.org/show_bug.cgi?id=597865

diff --git a/docs/reference/gtk/tmpl/gtkaboutdialog.sgml b/docs/reference/gtk/tmpl/gtkaboutdialog.sgml
deleted file mode 100644 (file)
index 6aac589..0000000
--- a/docs/reference/gtk/tmpl/gtkaboutdialog.sgml
+++ /dev/null
@@ -1,475 +0,0 @@
-<!-- ##### SECTION Title ##### -->
-GtkAboutDialog
-
-<!-- ##### SECTION Short_Description ##### -->
-Display information about an application
-
-<!-- ##### SECTION Long_Description ##### -->
-<para>
-The #GtkAboutDialog offers a simple way to display information about
-a program like its logo, name, copyright, website and license. It is
-also possible to give credits to the authors, documenters, translators
-and artists who have worked on the program. An about dialog is typically
-opened when the user selects the <literal>About</literal> option from 
-the <literal>Help</literal> menu. All parts of the dialog are optional.
-</para>
-<para>
-About dialog often contain links and email addresses. #GtkAboutDialog 
-supports this by offering global hooks, which are called when the user
-clicks on a link or email address, see gtk_about_dialog_set_email_hook()
-and gtk_about_dialog_set_url_hook(). Email addresses in the 
-authors, documenters and artists properties are recognized by looking for
-<literal>&lt;user@<!-- -->host&gt;</literal>, URLs are 
-recognized by looking for <literal>http://url</literal>, with 
-<literal>url</literal> extending to the next space, tab or line break.
-</para>
-<para id="gtk-about-dialog-hook-setup">
-Since 2.18 #GtkAboutDialog provides default website and email hooks that use
-gtk_show_uri().
-</para>
-<para>
-If you want provide your own hooks overriding the default ones, it is important
-to do so before setting the website and email URL properties, like this:
-</para>
-<informalexample><programlisting>
-gtk_about_dialog_set_url_hook (GTK_ABOUT_DIALOG (dialog), launch_url, NULL, NULL);
-gtk_about_dialog_set_website (GTK_ABOUT_DIALOG (dialog), app_url);
-</programlisting></informalexample>
-<para>
-To disable the default hooks, you can pass %NULL as the hook func. Then,
-the #GtkAboutDialog widget will not display the website or the
-email addresses as clickable.
-</para>
-<para>
-To make constructing a #GtkAboutDialog as convenient as possible, you can
-use the function gtk_show_about_dialog() which constructs and shows a dialog 
-and keeps it around so that it can be shown again.
-</para>
-<para>
-Note that GTK+ sets a default title of <literal>_("About &percnt;s")</literal> 
-on the dialog window (where &percnt;s is replaced by the name of the 
-application, but in order to ensure proper translation of the title, 
-applications should set the title property explicitly when constructing 
-a #GtkAboutDialog, as shown in the following example:
-</para>
-<informalexample><programlisting>
-gtk_show_about_dialog (NULL, 
-                       "program-name", "ExampleCode",
-                       "logo", example_logo,
-                       "title" _("About ExampleCode"),
-                       NULL);
-</programlisting></informalexample>
-<para>
-Note that prior to GTK+ 2.12, the #GtkAboutDialog:program-name property
-was called "name". This was changed to avoid the conflict with the
-#GtkWidget:name property.
-</para>
-
-<!-- ##### SECTION See_Also ##### -->
-<para>
-#GTK_STOCK_ABOUT
-</para>
-
-<!-- ##### SECTION Stability_Level ##### -->
-
-
-<!-- ##### STRUCT GtkAboutDialog ##### -->
-<para>
-The <structname>GtkAboutDialog</structname> struct contains
-only private fields and should not be directly accessed.
-</para>
-
-
-<!-- ##### ARG GtkAboutDialog:artists ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkAboutDialog:authors ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkAboutDialog:comments ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkAboutDialog:copyright ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkAboutDialog:documenters ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkAboutDialog:license ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkAboutDialog:logo ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkAboutDialog:logo-icon-name ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkAboutDialog:program-name ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkAboutDialog:translator-credits ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkAboutDialog:version ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkAboutDialog:website ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkAboutDialog:website-label ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkAboutDialog:wrap-license ##### -->
-<para>
-
-</para>
-
-<!-- ##### FUNCTION gtk_about_dialog_new ##### -->
-<para>
-
-</para>
-
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_about_dialog_get_name ##### -->
-<para>
-
-</para>
-
-@about: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_about_dialog_set_name ##### -->
-<para>
-
-</para>
-
-@about: 
-@name: 
-
-
-<!-- ##### FUNCTION gtk_about_dialog_get_program_name ##### -->
-<para>
-
-</para>
-
-@about: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_about_dialog_set_program_name ##### -->
-<para>
-
-</para>
-
-@about: 
-@name: 
-
-
-<!-- ##### FUNCTION gtk_about_dialog_get_version ##### -->
-<para>
-
-</para>
-
-@about: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_about_dialog_set_version ##### -->
-<para>
-
-</para>
-
-@about: 
-@version: 
-
-
-<!-- ##### FUNCTION gtk_about_dialog_get_copyright ##### -->
-<para>
-
-</para>
-
-@about: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_about_dialog_set_copyright ##### -->
-<para>
-
-</para>
-
-@about: 
-@copyright: 
-
-
-<!-- ##### FUNCTION gtk_about_dialog_get_comments ##### -->
-<para>
-
-</para>
-
-@about: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_about_dialog_set_comments ##### -->
-<para>
-
-</para>
-
-@about: 
-@comments: 
-
-
-<!-- ##### FUNCTION gtk_about_dialog_get_license ##### -->
-<para>
-
-</para>
-
-@about: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_about_dialog_set_license ##### -->
-<para>
-
-</para>
-
-@about: 
-@license: 
-
-
-<!-- ##### FUNCTION gtk_about_dialog_get_wrap_license ##### -->
-<para>
-
-</para>
-
-@about: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_about_dialog_set_wrap_license ##### -->
-<para>
-
-</para>
-
-@about: 
-@wrap_license: 
-
-
-<!-- ##### FUNCTION gtk_about_dialog_get_website ##### -->
-<para>
-
-</para>
-
-@about: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_about_dialog_set_website ##### -->
-<para>
-
-</para>
-
-@about: 
-@website: 
-
-
-<!-- ##### FUNCTION gtk_about_dialog_get_website_label ##### -->
-<para>
-
-</para>
-
-@about: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_about_dialog_set_website_label ##### -->
-<para>
-
-</para>
-
-@about: 
-@website_label: 
-
-
-<!-- ##### FUNCTION gtk_about_dialog_get_authors ##### -->
-<para>
-
-</para>
-
-@about: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_about_dialog_set_authors ##### -->
-<para>
-
-</para>
-
-@about: 
-@authors: 
-
-
-<!-- ##### FUNCTION gtk_about_dialog_get_artists ##### -->
-<para>
-
-</para>
-
-@about: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_about_dialog_set_artists ##### -->
-<para>
-
-</para>
-
-@about: 
-@artists: 
-
-
-<!-- ##### FUNCTION gtk_about_dialog_get_documenters ##### -->
-<para>
-
-</para>
-
-@about: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_about_dialog_set_documenters ##### -->
-<para>
-
-</para>
-
-@about: 
-@documenters: 
-
-
-<!-- ##### FUNCTION gtk_about_dialog_get_translator_credits ##### -->
-<para>
-
-</para>
-
-@about: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_about_dialog_set_translator_credits ##### -->
-<para>
-
-</para>
-
-@about: 
-@translator_credits: 
-
-
-<!-- ##### FUNCTION gtk_about_dialog_get_logo ##### -->
-<para>
-
-</para>
-
-@about: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_about_dialog_set_logo ##### -->
-<para>
-
-</para>
-
-@about: 
-@logo: 
-
-
-<!-- ##### FUNCTION gtk_about_dialog_get_logo_icon_name ##### -->
-<para>
-
-</para>
-
-@about: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_about_dialog_set_logo_icon_name ##### -->
-<para>
-
-</para>
-
-@about: 
-@icon_name: 
-
-
-<!-- ##### USER_FUNCTION GtkAboutDialogActivateLinkFunc ##### -->
-<para>
-The type of a function which is called when a URL or email
-link is activated. 
-</para>
-
-@about: the #GtkAboutDialog in which the link was activated
-@link_: the URL or email address to which the activated link points
-@data: user data that was passed when the function was registered
-  with gtk_about_dialog_set_email_hook() or 
-  gtk_about_dialog_set_url_hook()
-
-
-<!-- ##### FUNCTION gtk_about_dialog_set_email_hook ##### -->
-<para>
-
-</para>
-
-@func: 
-@data: 
-@destroy: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_about_dialog_set_url_hook ##### -->
-<para>
-
-</para>
-
-@func: 
-@data: 
-@destroy: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_show_about_dialog ##### -->
-<para>
-
-</para>
-
-@parent: 
-@first_property_name: 
-@Varargs: 
-
-

diff --git a/gtk/gtkaboutdialog.c b/gtk/gtkaboutdialog.c
index 91d30fe344d4812d84c9a9a9ede7a8f8017cd72b..6498d1df372913b6e05494a12f68669605103810 100644 (file)
--- a/gtk/gtkaboutdialog.c
+++ b/gtk/gtkaboutdialog.c
@@ -57,6 +57,67 @@
 
 #include "gtkalias.h"
 
+
+/**
+ * SECTION:gtkaboutdialog
+ * @Short_description: Display information about an application
+ * @Title: GtkAboutDialog
+ * @See_also:#GTK_STOCK_ABOUT
+ *
+ * The #GtkAboutDialog offers a simple way to display information about
+ * a program like its logo, name, copyright, website and license. It is
+ * also possible to give credits to the authors, documenters, translators
+ * and artists who have worked on the program. An about dialog is typically
+ * opened when the user selects the <literal>About</literal> option from
+ * the <literal>Help</literal> menu. All parts of the dialog are optional.
+ *
+ * About dialog often contain links and email addresses. #GtkAboutDialog
+ * supports this by offering global hooks, which are called when the user
+ * clicks on a link or email address, see gtk_about_dialog_set_email_hook()
+ * and gtk_about_dialog_set_url_hook(). Email addresses in the
+ * authors, documenters and artists properties are recognized by looking for
+ * <literal><user@<!-- -->host></literal>, URLs are
+ * recognized by looking for <literal>http://url</literal>, with
+ * <literal>url</literal> extending to the next space, tab or line break.
+ *
+ * <para id="gtk-about-dialog-hook-setup">
+ * Since 2.18 #GtkAboutDialog provides default website and email hooks that use
+ * gtk_show_uri().
+ *
+ * If you want provide your own hooks overriding the default ones, it is important
+ * to do so before setting the website and email URL properties, like this:
+ *
+ * <informalexample><programlisting>
+ * gtk_about_dialog_set_url_hook (GTK_ABOUT_DIALOG (dialog), launch_url, NULL, NULL);
+ * gtk_about_dialog_set_website (GTK_ABOUT_DIALOG (dialog), app_url);
+ * </programlisting></informalexample>
+ * To disable the default hooks, you can pass %NULL as the hook func. Then,
+ * the #GtkAboutDialog widget will not display the website or the
+ * email addresses as clickable.
+ *
+ * To make constructing a #GtkAboutDialog as convenient as possible, you can
+ * use the function gtk_show_about_dialog() which constructs and shows a dialog
+ * and keeps it around so that it can be shown again.
+ *
+ * Note that GTK+ sets a default title of <literal>_("About &percnt;s")</literal>
+ * on the dialog window (where &percnt;s is replaced by the name of the
+ * application, but in order to ensure proper translation of the title,
+ * applications should set the title property explicitly when constructing
+ * a #GtkAboutDialog, as shown in the following example:
+ *
+ * <informalexample><programlisting>
+ * gtk_show_about_dialog (NULL,
+ *                        "program-name", "ExampleCode",
+ *                        "logo", example_logo,
+ *                        "title" _("About ExampleCode"),
+ *                        NULL);
+ * </programlisting></informalexample>
+ * Note that prior to GTK+ 2.12, the #GtkAboutDialog:program-name property
+ * was called "name". This was changed to avoid the conflict with the
+ * #GtkWidget:name property.
+ */
+
+
 static GdkColor default_link_color = { 0, 0, 0, 0xeeee };
 static GdkColor default_visited_link_color = { 0, 0x5555, 0x1a1a, 0x8b8b };
 

diff --git a/gtk/gtkaboutdialog.h b/gtk/gtkaboutdialog.h
index 02f2fbec03d3a499a385c7cda7da7a56e34262ce..efb50b1cf05dd844c16a6c9664c9da102e2abfff 100644 (file)
--- a/gtk/gtkaboutdialog.h
+++ b/gtk/gtkaboutdialog.h
@@ -43,6 +43,12 @@ G_BEGIN_DECLS
 typedef struct _GtkAboutDialog        GtkAboutDialog;
 typedef struct _GtkAboutDialogClass   GtkAboutDialogClass;
 
+/**
+ * GtkAboutDialog:
+ *
+ * The <structname>GtkAboutDialog</structname> struct contains
+ * only private fields and should not be directly accessed.
+ */
 struct _GtkAboutDialog 
 {
   GtkDialog parent_instance;
@@ -118,6 +124,17 @@ G_CONST_RETURN gchar  *gtk_about_dialog_get_logo_icon_name     (GtkAboutDialog
 void                   gtk_about_dialog_set_logo_icon_name     (GtkAboutDialog  *about,
                                                                const gchar     *icon_name);
 
+/**
+ * GtkAboutDialogActivateLinkFunc:
+ * @about: the #GtkAboutDialog in which the link was activated
+ * @link_: the URL or email address to which the activated link points
+ * @data: user data that was passed when the function was registered
+ *  with gtk_about_dialog_set_email_hook() or
+ *  gtk_about_dialog_set_url_hook()
+ *
+ * The type of a function which is called when a URL or email
+ * link is activated.
+ */
 typedef void (* GtkAboutDialogActivateLinkFunc) (GtkAboutDialog *about,
                                                 const gchar    *link_,
                                                 gpointer        data);